postcss-load-config

What is postcss-load-config?

The postcss-load-config package is used to load PostCSS configurations automatically. It helps in finding and loading a PostCSS configuration file, which can be in different formats like .postcssrc, postcss.config.js, or directly in package.json. It simplifies the process of setting up PostCSS by abstracting the configuration loading logic.

What are postcss-load-config's main functionalities?

Loading PostCSS Configurations

This feature allows you to load the PostCSS configuration from a file or package.json. The code sample demonstrates how to use the package to load the configuration and then use it to process CSS with PostCSS.

const postcssLoadConfig = require('postcss-load-config');

postcssLoadConfig().then(({ plugins, options }) => {
  // Use the loaded plugins and options to process your CSS with PostCSS
  postcss(plugins).process(yourCss, options);
}).catch((error) => {
  console.error('Failed to load PostCSS config:', error);
});

Other packages similar to postcss-load-config

cosmiconfig

Cosmiconfig is a package that searches for and loads configuration for your program. It supports several file formats and locations for the configurations. It is similar to postcss-load-config but is more generic and not limited to PostCSS configurations.

webpack-config-loader

webpack-config-loader is a package that helps load and customize webpack configurations. It is similar to postcss-load-config in that it abstracts the configuration loading process, but it is specific to webpack rather than PostCSS.

require-from-string

require-from-string allows you to require modules from a string of code. It is similar to postcss-load-config in that it can be used to load configurations dynamically, but it does not have the built-in logic to search for configuration files.

README

Load Config

Install

npm i -D postcss-load-config

Usage

npm i -S|-D postcss-plugin

Install plugins and save them to your package.json dependencies/devDependencies.

package.json

Create postcss section in your projects package.json.

App
  |– client
  |– public
  |
  |- package.json

{
  "postcss": {
    "parser": "sugarss",
    "map": false,
    "from": "/path/to/src.sss",
    "to": "/path/to/dest.css",
    "plugins": {
      "postcss-plugin": {}
    }
  }
}

.postcssrc

Create a .postcssrc file in JSON or YAML format.

It's also allowed to use extensions (.postcssrc.json or .postcssrc.yaml). That could help your text editor to properly interpret the file.

App
  |– client
  |– public
  |
  |- (.postcssrc|.postcssrc.json|.postcssrc.yaml)
  |- package.json

JSON

{
  "parser": "sugarss",
  "map": false,
  "from": "/path/to/src.sss",
  "to": "/path/to/dest.css",
  "plugins": {
    "postcss-plugin": {}
  }
}

YAML

parser: sugarss
map: false
from: "/path/to/src.sss"
to: "/path/to/dest.css"
plugins:
  postcss-plugin: {}

postcss.config.js or .postcssrc.js

You may need some JavaScript logic to generate your config. For this case you can use a file named postcss.config.js or .postcssrc.js.

App
  |– client
  |– public
  |
  |- (postcss.config.js|.postcssrc.js)
  |- package.json

You can export the config as an {Object}

module.exports = {
  parser: 'sugarss',
  map: false,
  from: '/path/to/src.sss',
  to: '/path/to/dest.css',
  plugins: {
    'postcss-plugin': {}
  }
}

Or export a {Function} that returns the config (more about the param ctx below)

module.exports = (ctx) => ({
  parser: ctx.parser ? 'sugarss' : false,
  map: ctx.env === 'development' ? ctx.map : false,
  from: ctx.from,
  to: ctx.to,
  plugins: {
    'postcss-plugin': ctx.plugin
  }
})

Plugins can be loaded in either using an {Object} or an {Array}.

{Object}

module.exports = (ctx) => ({
  ...options
  plugins: {
    'postcss-plugin': ctx.plugin
  }
})

{Array}

module.exports = (ctx) => ({
  ...options
  plugins: [
    require('postcss-plugin')(ctx.plugin)
  ]
})

:warning: When using an Array, make sure to require() them.

Options

parser:

'parser': 'sugarss'

syntax:

'syntax': 'postcss-scss'

stringifier:

'stringifier': 'midas'

map:

'map': 'inline'

from:

from: 'path/to/src.css'

to:

to: 'path/to/dest.css'

Plugins

Options

{} || null: Plugin loads with defaults.

'postcss-plugin': {} || null

:warning: {} must be an empty object

[Object]: Plugin loads with given options.

'postcss-plugin': { option: '', option: '' }

false: Plugin will not be loaded.

'postcss-plugin': false

Order

Plugin order is determined by declaration in the plugins section.

{
  plugins: {
    'postcss-plugin': {}, // plugins[0]
    'postcss-plugin': {}, // plugins[1]
    'postcss-plugin': {}  // plugins[2]
  }
}

Context

When using a function (postcss.config.js or .postcssrc.js), it is possible to pass context to postcss-load-config, which will be evaluated while loading your config. By default ctx.env (process.env.NODE_ENV) and ctx.cwd (process.cwd()) are available.

Examples

postcss.config.js

module.exports = (ctx) => ({
  parser: ctx.parser ? 'sugarss' : false,
  map: ctx.env === 'development' ? ctx.map : false,
  plugins: {
    'postcss-import': {},
    'postcss-nested': {},
    cssnano: ctx.env === 'production' ? {} : false
  }
})

"scripts": {
  "build": "NODE_ENV=production node postcss",
  "start": "NODE_ENV=development node postcss"
}

const { readFileSync } = require('fs')

const postcss = require('postcss')
const postcssrc = require('postcss-load-config')

const css = readFileSync('index.sss', 'utf8')

const ctx = { parser: true, map: 'inline' }

postcssrc(ctx).then(({ plugins, options }) => {
  postcss(plugins)
    .process(css, options)
    .then((result) => console.log(result.css))
})

"scripts": {
  "build": "NODE_ENV=production gulp",
  "start": "NODE_ENV=development gulp"
}

const { task, src, dest, series, watch } = require('gulp')

const postcss = require('gulp-postcssrc')

const css = () => {
  src('src/*.css')
    .pipe(postcss())
    .pipe(dest('dest'))
})

task('watch', () => {
  watch(['src/*.css', 'postcss.config.js'], css)
})

task('default', series(css, 'watch'))

"scripts": {
  "build": "NODE_ENV=production webpack",
  "start": "NODE_ENV=development webpack-dev-server"
}

module.exports = (env) => ({
  module: {
    rules: [
      {
        test: /\.css$/
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: { importLoaders: 1 } }
          },
          'postcss-loader'
        ]
      }
    ]
  }
})

Maintainers

Michael Ciniawsky

Mateusz Derks

Contributors

Ryan Dunckel

Patrick Gilday

Dalton Santos

Changelog

1.2.0 (2017-02-13)

Features

• index: allow extensions for .postcssrc (0d3bf35)

<a name="1.1.0"></a>